From: Paul Donald Date: Tue, 4 Nov 2025 14:26:53 +0000 (+0100) Subject: readme: rewrite in markdown X-Git-Url: http://git.openwrt.org/%22https:/collectd.org//%22http:/www.crowdsec.net/%22/%22https:/collectd.org/%22http:/www.crowdsec.net/%22?a=commitdiff_plain;h=17ef5f40d48af51391ff2901bea5bef8d96448af;p=project%2Fodhcp6c.git readme: rewrite in markdown Convert original README to markdown. Signed-off-by: Paul Donald Link: https://github.com/openwrt/odhcp6c/pull/111 Signed-off-by: Álvaro Fernández Rojas --- diff --git a/README b/README deleted file mode 100644 index e8a725a..0000000 --- a/README +++ /dev/null @@ -1,149 +0,0 @@ -odhcp6c - Embedded DHCPv6 Client - - -** Abstract ** - -odhcp6c is a minimal DHCPv6 and RA-client for use in embedded Linux systems -especially routers. It compiles to only about 35 KB (-Os -s). - - -** Features ** - -1. IPv6 bootstrap from different environments with autodetection - a) RA only - b) RA + stateless DHCPv6 - c) RA + stateful DHCPv6 (either IA_NA or IA_PD or both) - -2. Handling of non-temporary addresses (IA_NA) - a) handling of valid and preferred lifetimes - b) automatic fallback to stateless or PD-only mode - -3. Support for DHCPv6 extension - a) Reconfigure-Messages - b) Prefix Delegation (including handling of valid and preferred lifetimes) - c) Prefix Exclusion - d) DNS Configuration Options - e) NTP Options - f) SIP Options - g) Information-Refresh Options - h) Configurable SOL_MAX_RT - i) DS-Lite AFTR-Name Option - j) Softwire address and port mapped clients (MAP, LW4over6) - j) CER-ID (experimental) - k) Server unicast Option - -4. Support for requesting and parsing Router Advertisements - a) parsing of prefixes, routes, MTU and RDNSS options - - -** Compiling ** - -odhcp6c uses cmake: -* To prepare a Makefile use: "cmake ." -* To build / install use: "make" / "make install" afterwards. -* To build DEB or RPM packages use: "make package" afterwards. - - -** State Script ** - -The state script is called whenever the DHCPv6 state changes. -The script is called with the following parameters: - - -States: -* started The DHCPv6 client has been started -* bound A suitable server was found and addresses or prefixes acquired -* informed A stateless information request returned updated information -* updated Updated information was received from the DHCPv6 server -* ra-updated Updated information was received from via Router Advertisement -* rebound The DHCPv6 client switched to another server -* unbound The DHCPv6 client lost all DHCPv6 servers and will restart -* stopped The DHCPv6 client has been stopped - - -Environment: -* RDNSS A space-separated list of recursive DNS servers -* DOMAINS A space-separated list of DNS search domains -* SNTP_IP A space-separated list of SNTP server IP addresses -* SNTP_FQDN A space-separated list of SNTP server FQDNs -* SIP_IP A space-separated list of SIP servers -* SIP_DOMAIN A space-separated list of SIP domains -* OPTION_ Custom option received as base-16 -* PREFIXES A space-separated list of prefixes currently assigned - Format: /,preferred,valid[,excluded=/][,class=] -* ADDRESSES A space-separated list of addresses currently assigned - Format:
/,preferred,valid -* RA_ADDRESSES A space-separated list of addresses from RA-prefixes - Format:
/,preferred,valid -* RA_ROUTES A space-separated list of routes from the RA - Format:
/,gateway,valid,metric -* RA_DNS A space-separated list of recursive DNS servers from the RA -* RA_DOMAINS A space-separated list of DNS search domains from the RA -* RA_HOPLIMIT Highest hop-limit received in RAs -* RA_MTU MTU-value received in RA -* RA_REACHABLE ND Reachability time -* RA_RETRANSMIT ND Retransmit time -* AFTR The DS-Lite AFTR domain name -* MAPE / MAPT / LW4O6 Softwire rules for MAPE, MAPT and LW4O6 - -** Ubus Integration ** - -Build with ENABLE_UBUS flag to connect odhcp6c to ubus. Object is registered at : "odhcp6c.{ifname}." - -Events are emitted whenever the DHCPv6 state changes and can replace the use of a state script. The variables are the same as those defined in the State Script section. - -The following RPC methods are available: - -* *get_state()* : Returns the DHCPv6 state - - OUT : see State Script section -* *get_statistics()* : Returns the packet statistics - - OUT : - - *dhcp_solicit* : Total number of SOLICIT messages sent - - *dhcp_advertise* : Total number of ADVERTISE messages received - - *dhcp_request* : Total number of REQUEST messages sent - - *dhcp_confirm* : Total number of CONFIRM messages sent - - *dhcp_renew* : Total number of RENEW messages sent - - *dhcp_rebind* : Total number of REBIND messages sent - - *dhcp_reply* : Total number of REPLY messages received - - *dhcp_release* : Total number of RELEASE messages sent - - *dhcp_decline* : Total number of DECLINE messages sent - - *dhcp_reconfigure* : Total number of RECONFIGURE messages received - - *dhcp_information_request* : Total number of INFORMATION-REQUEST messages sent - - *dhcp_discarded_packets* : Total number of discarded DHCP packets - - *dhcp_transmit_failures* : Total number of DHCP messages that failed to be transmitted -* *reset_statistics()* : Reset packet statistics -* *reconfigure_dhcp(IN)* : Reconfigure DHCP settings - - IN (optional): - - *dscp* (int) : DSCP value used for DHCP packets - - *release* (bool) : Send a RELEASE message on exit/reset - - *sol_timeout* (int) : Maximum timeout for DHCPv6-SOLICIT - - *sk_prio* (int) : Packet kernel priority - - *opt_requested* (int[]) : Options to be requested - - *opt_strict* (bool) : Do not request any options except those specified - - *opt_reconfigure* (bool) : Send Accept Reconfigure option - - *opt_fqdn* (bool) : Send Client FQDN option - - *opt_unicast* (bool) : Ignore Server Unicast option - - *opt_send* (string[]) : Options to be sent - - *req_addresses* (string{try|force|none}) : Request addresses - - *req_prefixes* (int) : Request Prefixes (0 = auto) - - *stateful_only* (bool) : Discard advertisements without any address or prefix proposed - - *irt_default* (int) : Default information refresh time (expressed in seconds) - - *irt_min* (int) : Minimum information refresh time (expressed in seconds) - - *rand_factor* (int) : Randomization factor for retransmission timeout - - *msg_solicit* (table) : Retransmission settings for SOLICIT - - *msg_request* (table) : Retransmission settings for REQUEST - - *msg_renew* (table) : Retransmission settings for RENEW - - *msg_rebind* (table) : Retransmission settings for REBIND - - *msg_release* (table) : Retransmission settings for RELEASE - - *msg_decline* (table) : Retransmission settings for DECLINE - - *msg_inforeq* (table) : Retransmission settings for INFORMATION-REQUEST - - *auth_protocol* (string) : Authentication protocol to be used ("None","ConfigurationToken", "ReconfigureKeyAuthentication") - - *auth_token* (string) : Authentication token to be used when AuthenticationProtocol is set to ConfigurationToken -* *renew()* : Force transmission of RENEW/INFORMATION-REQUEST messages -* *release()* : Force transmission of RELEASE message and start new cycle - -Input arguments for retransmission settings : - - *delay_max* (int) : Maximum delay of first message (expressed in seconds) - - *timeout_init* (int) : Initial message timeout (expressed in seconds) - - *timeout_max* (int) : Initial message timeout (expressed in seconds) - - *rc_max* (int) : Maximum message retry attempts \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..a12dff7 --- /dev/null +++ b/README.md @@ -0,0 +1,93 @@ +# odhcp6c - Embedded DHCPv6 Client + + +### Abstract + +odhcp6c is a minimal DHCPv6 and RA-client for use in embedded Linux systems +especially routers. + + +## Features + +1. IPv6 bootstrap from different environments with autodetection + * RA only + * RA + stateless DHCPv6 + * RA + stateful DHCPv6 (either IA_NA or IA_PD or both) + +2. Handling of non-temporary addresses (IA_NA) + * handling of valid and preferred lifetimes + * automatic fallback to stateless or PD-only mode + +3. Support for DHCPv6 extension + * Reconfigure-Messages + * Prefix Delegation (including handling of valid and preferred lifetimes) + * Prefix Exclusion + * DNS Configuration Options + * NTP Options + * SIP Options + * Information-Refresh Options + * Configurable SOL_MAX_RT + * DS-Lite AFTR-Name Option + * Softwire address and port mapped clients (MAP, LW4over6) + * CER-ID (experimental) + * Server unicast Option + +4. Support for requesting and parsing Router Advertisements + * parsing of prefixes, routes, MTU and RDNSS options + + +## Compiling + +odhcp6c uses cmake: +* To prepare a Makefile use: `cmake`. +* To build / install use: `make` / `make install` afterwards. +* To build DEB or RPM packages use: `make package` afterwards. + + +## State Script + +The state script is called whenever the DHCPv6 state changes. +The script is called with the following parameters: `` `` + +| State | Description | +|-----------------------------------|-------------------------------------------------------------------| +| `started` | The DHCPv6 client has been started | +| `bound` | A suitable server was found and addresses or prefixes acquired | +| `informed` | A stateless information request returned updated information | +| `updated` | Updated information was received from the DHCPv6 server | +| `ra-updated` | Updated information was received via Router Advertisements | +| `rebound` | The DHCPv6 client switched to another server | +| `unbound` | The DHCPv6 client lost all DHCPv6 servers and will restart | +| `stopped` | The DHCPv6 client has been stopped | + + + + +| Environment | Description | +|-----------------------------------|-------------------------------------------------------------------| +| `RDNSS` | A space-separated list of recursive DNS servers | +| `DOMAINS` | A space-separated list of DNS search domains | +| `SNTP_IP` | A space-separated list of SNTP server IP addresses | +| `SNTP_FQDN` | A space-separated list of SNTP server FQDNs | +| `SIP_IP` | A space-separated list of SIP servers | +| `SIP_DOMAIN` | A space-separated list of SIP domains | +| `OPTION_` | Custom option received as base-16 | +| `PREFIXES` | A space-separated list of prefixes currently assigned | +| | Format: `/,preferred,valid[,excluded=/][,class=]`| +| `ADDRESSES` | A space-separated list of addresses currently assigned | +| | Format: `
/,preferred,valid` | +| `RA_ADDRESSES` | A space-separated list of addresses from RA-prefixes | +| | Format: `
/,preferred,valid` | +| `RA_ROUTES` | A space-separated list of routes from the RA | +| | Format: `
/,gateway,valid,metric` | +| `RA_DNS` | A space-separated list of recursive DNS servers from the RA | +| `RA_DOMAINS` | A space-separated list of DNS search domains from the RA | +| `RA_HOPLIMIT` | Highest hop-limit received in RAs | +| `RA_MTU` | MTU-value received in RA | +| `RA_REACHABLE` | ND Reachability time | +| `RA_RETRANSMIT` | ND Retransmit time | +| `AFTR` | The DS-Lite AFTR domain name | +| `MAPE` / `MAPT` / `LW4O6` | Softwire rules for MAPE, MAPT and LW4O6 | + + +